Skip to content

Add Qwen3-VL-4B support#4263

Merged
copybara-service[bot] merged 1 commit into
mainfrom
hengtaoguo-vl
Jun 26, 2026
Merged

Add Qwen3-VL-4B support#4263
copybara-service[bot] merged 1 commit into
mainfrom
hengtaoguo-vl

Conversation

@hengtaoguo

@hengtaoguo hengtaoguo commented Jun 24, 2026

Copy link
Copy Markdown
Collaborator

Description

This PR adds Qwen/Qwen3-VL-4B-Instruct (Qwen3-Omni vision encoder + Qwen3-4B dense decoder) to maxtext:

  • Add Qwen3-VL-4B model config and register Qwen/Qwen3-VL-4B-Instruct.
  • Wire Qwen3-VL into multimodal config validation, prompt/image preprocessing, embedding fusion, and vision bidirectional masking.
  • Add Qwen3-VL vision encoder/projector subclasses reusing the existing Qwen3 Omni vision tower implementation.
  • Extend vision RoPE handling to Qwen3 vision models.
  • Add HF config, HF shape metadata, parameter mappings, and conversion hooks for Qwen3-VL checkpoint conversion.
  • Preserve non-causal-LM HF config architectures during save when no causal LM mapping exists.

Tests

# Checkpoint conversion
python -m maxtext.checkpoint_conversion.to_maxtext src/maxtext/configs/base.yml model_name=qwen3-vl-4b base_output_directory=gs://hengtaoguo-maxtext-logs/checkpoints/qwen3-vl-4b/unscanned/2026-06-24-15-27 scan_layers=false hf_access_token=<your_token> weight_dtype=bfloat16 hardware=cpu skip_jax_distributed_system=True checkpoint_storage_use_ocdbt=False checkpoint_storage_use_zarr3=False --eager_load_method=safetensors --lazy_load_tensors=False
# Image decode check
python -m maxtext.inference.decode maxtext/configs/base.yml model_name=qwen3-vl-4b tokenizer_path=Qwen/Qwen3-VL-4B-Instruct tokenizer_type=huggingface load_parameters_path=gs://hengtaoguo-maxtext-logs/checkpoints/qwen3-vl-4b/unscanned/2026-06-24-15-27/0/items per_device_batch_size=1 run_name=ht_test scan_layers=false use_multimodal=true prompt=\'Describe\ this\ image\' image_path=\'tests/assets/test_image.jpg\' max_prefill_predict_length=512 max_target_length=768 ici_tensor_parallelism=4 override_model_config=true attention=\'dot_product\' hf_access_token=<your_token>

# Outputs
Input `<|im_start|>user
<|vision_start|><|image_pad|><|vision_end|>Describe this image<|im_end|>
<|im_start|>assistant
` -> `This image captures a vibrant, sunlit panoramic view of Seattle, Washington, under a clear blue sky. The most iconic landmark, the Space Needle, stands prominently in the center-left of the frame, its distinctive futuristic design rising above the surrounding urban landscape.
# Video decode check
python -m maxtext.inference.decode maxtext/configs/base.yml model_name=qwen3-vl-4b tokenizer_path=Qwen/Qwen3-VL-4B-Instruct tokenizer_type=huggingface load_parameters_path=gs://hengtaoguo-maxtext-logs/checkpoints/qwen3-vl-4b/unscanned/2026-06-24-15-27/0/items per_device_batch_size=1 run_name=ht_test scan_layers=false use_multimodal=true prompt=\'What\ is\ the\ classification\ of\ the\ single\ exhibit\ in\ this\ video\?\' video_path=\'tests/assets/test_video.mp4\' max_prefill_predict_length=1240 max_target_length=1280 ici_tensor_parallelism=4 override_model_config=true attention=\'dot_product\' hf_access_token=<your_token>

# Outputs
Input `<|im_start|>user
<|vision_start|><|video_pad|><|vision_end|>What is the classification of the single exhibit in thisvideo?<|im_end|>
<|im_start|>assistant
` -> `The exhibit in the video is a **dinosaur model**, specifically a **Tyrannosaurus rex** (or a similar large theropod dinosaur) displayed in a **museum or exhibition setting`

Checklist

Before submitting this PR, please make sure (put X in square brackets):

  • I have performed a self-review of my code. For an optional AI review, add the gemini-review label.
  • I have necessary comments in my code, particularly in hard-to-understand areas.
  • I have run end-to-end tests tests and provided workload links above if applicable.
  • I have made or will make corresponding changes to the doc if needed, including adding new documentation pages to the relevant Table of Contents (toctree directive) as explained in our documentation.

@codecov

codecov Bot commented Jun 24, 2026

Copy link
Copy Markdown

@github-actions

Copy link
Copy Markdown

🤖 Hi @hengtaoguo, I've received your request, and I'm working on it now! You can track my progress in the logs for more details.

@github-actions

Copy link
Copy Markdown

🤖 I'm sorry @hengtaoguo, but I was unable to process your request. Please see the logs for more details.

@github-actions

Copy link
Copy Markdown

🤖 I'm sorry @hengtaoguo, but I was unable to process your request. Please see the logs for more details.

Comment thread src/maxtext/checkpoint_conversion/utils/param_mapping.py Outdated
Comment thread src/maxtext/checkpoint_conversion/utils/param_mapping.py Outdated
Comment thread src/maxtext/utils/globals.py Outdated
@copybara-service copybara-service Bot merged commit 7a80e6c into main Jun 26, 2026
60 of 61 checks passed
@copybara-service copybara-service Bot deleted the hengtaoguo-vl branch June 26, 2026 17:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants